FolderItem Class
FolderItem class objects represent files, applications, or folders. They are created by calling a method such as GetFolderItem or via the Parent or Item properties of other FolderItem objects.
More information available in parent classes: Object
Notes
Specifying Pathnames
Use the Volume function, the Parent property of the FolderItem class, and the Child method of the Folderitem class to specify pathnames. The Volume function returns a reference to any volume on the user's computer. Pass it a number that indicates the desired volume. Zero is the boot volume. You can get the number of volumes with the VolumeCount function. For example, to get a FolderItem for Microsoft Word in the Program Files folder on the boot volume, you can use the following line of code (The line continuation keyword, _, is used to split the line into two printed lines).
f= Volume(0).Child("Program Files").Child("Microsoft Office"). _
Child("OFFICE11").Child("WINWORD.EXE")
The GetFolderItem function can be used to get a FolderItem for an item in the current directory (the directory that contains the application or the REALbasic IDE if you are debugging the application). Simply pass it the name of the item. For example, the following returns a FolderItem for the directory "MyTemplates" in the current folder:
If the document or directory does not exist, the Exists property of the FolderItem is False.
If you pass the empty string to GetFolderItem, it returns the FolderItem for the directory that contains the application.
The Parent property of the FolderItem class enables you to navigate one level up in the hierarchy. For example, the following gives you the FolderItem for the directory that contains the directory that contains the application:
Mac OS X is based on BSD Unix which uses "/" as the separator. However, because REALbasic and all applications made with REALbasic are Carbon applications on Mac OS X, they continue to use ":" as the separator. The one exception is when accessing files via the Shell class. In this case, you would use the same separator that you use on the command line.
FolderItem Constructor
When you create a FolderItem with the New command, you can pass the full or relative path to the new FolderItem as an optional parameter. For example:
specifies the name of the new FolderItem and it is located in the same folder as the REALbasic application (if you're running in the IDE) or the same folder as the built application.
Copy Constructor
You can create a copy of a FolderItem by passing the FolderItem to be copied to the constructor. The result is a copy of the passed FolderItem rather than a reference to it. For example:
If you pass a Nil FolderItem, you will raise a NilObjectException.
Shell Paths and Regular Paths
If you pass the optional parameter for path, you can also pass an optional second parameter indicating whether the path is a ShellPath, a "regular" path, or a path in the form of a URL. FolderItem has three class constants that you use to indicate this, PathTypeAbsolute, PathTypeURL, and PathTypeShell. For example:
You cannot pass a non-absolute Shell path. Attempting to do so will result in an UnsupportedFormatException.
If you use PathTypeURL, the URL must begin with "file:///".
You can also create a FolderItem without passing any parameters. It works the same as passing an empty text string.
Picture Formats
The SaveAsPicture method has an optional second parameter that enables you to specify the format in which the picture will be saved. Formats in the range of 0-99 are reserved for meta-formats. Meta-formats map to a various concrete formats based on the target, the data being saved, or other criteria (The mappings may change in future versions of REALbasic).
The numbers 100-199 are reserved for formats that are supported on multiple platforms (currently none).
200-299 are reserved for formats that are supported on the Macintosh.
300-399 are reserved for formats supported on Windows.
x00-x49 are vector formats, while x50-x99 are raster formats.
MetaFormats
| Value | Class Constant | Compatibility | Description |
| 0 | SaveAsMostCompatible | MostCompatible | Most widely-used format for the platform Mac = PICT Win32 = BMP) |
| 1 | SaveAsMostComplete | MostComplete | Format most likely to retain all vector info Mac = PICT Win32 = EMF) |
| 2 | SaveAsDefault | Default | DefaultVector or DefaultRaster, depending on picture data Mac = PICT Win32 vector=EMF Win32 raster= BMP |
| 3 | SaveAsDefaultVector | DefaultVector | Platform's standard vector format Mac = PICT Win32 = EMF) |
| 4 | SaveAsDefaultRaster | DefaultRaster | Platform's standard raster format Mac = Raster PICT Win32 = BMP) |
Macintosh Formats
| Value | Class Constant | Format | Description |
| 100 | SaveAsMacintoshPICT | PICT | Includes simple vector data. |
| 250 | SaveAsMacintoshRasterPICT | RasterPICT | Flattens all vector data to pixels. |
Win32 Formats
| Value | Class Constant | Format | Description |
| 300 | SaveAsWindowsWMF | WMF | Windows Metafile format (old vector format). |
| 301 | SaveAsWindowsEMF | EMF | Extended Metafile format (newer vector format). |
| 350 | SaveAsWindowsBMP | BMP | Windows bitmap format. |
FolderItem Error Constants
To determine which error code was returned in the LastErrorCode property, you can test it against one of the FolderItem error constants. They are given in the following table:
| Error Code | Constant | Description |
| NoError | No error occurred. | |
| 100 | DestDoesNotExistError | Destination does not exist. You will get this error only on CopyFileTo and MoveFileTo. |
| 101 | FileNotFound | The File was not found. |
| 102 | AccessDenied | Access was denied. |
| 103 | NotEnoughMemory | You ran out of memory. |
| 104 | FileInUse | The file is in use. |
| 105 | InvalidName | You used an Invalid name. |
Cross Platform Formats
No cross-platform formats are currently implemented.
Unrecognized formats or formats not supported for the built target will result in an UnsupportedFormatException. The Message property of the exception will contain additional information in as to what went wrong.
Aliases
If a FolderItem is actually an alias to a FolderItem, the alias is automatically resolved when the FolderItem is accessed unless you use TrueChild and TrueItem (Aliases for Win32 do not get resolved with Item and Child). They return the item itself, even if it is an alias. Use the Alias property to determine whether the FolderItem is an alias.
For more information on File Types, see the chapter called "Working With Files" in the User's Guide.
Movies
The OpenResourceMovie method allows you to get a movie stored in a MooV resource inside a file or application (Macintosh only). Prior to QuickTime 4.0, the actual movie in a QuickTime movie file was stored in a MooV resource. In QuickTime 4.0 (and above), the movie is stored in the data fork.
Examples
This example puts the names of all the items on the Desktop that are stored on the boot volume into ListBox1.
Dim f as FolderItem
f= DesktopFolder
n=f.count
If n>0 then
For i=1 to n
ListBox1.addrow f.item(i).name
Next
End if
Exception err as NilObjectException
MsgBox "File not Found"
This example uses MoveFileTo. The source file will be deleted and moved into the destination folder.
g= Volume(0).Child("targetFolder")
f= Volume(0).Child("ReleaseNotes")
If f <> Nil and g <> Nil then
f.MoveFileTo(g)
MsgBox "success!"
else
MsgBox "Files not found"
end if
The following example creates a text file, changes the Creator from the default creator of "R*ch" to "ttxt", and writes some data to the file.
Dim stream as TextOutputStream
f= GetSaveFolderItem("TEXT","Daily Planet Staff")
stream=f.CreateTextFile
f.MacCreator="ttxt"
Stream.WriteLine ("Perry White")
Stream.WriteLine ("Lois Lane")
Stream.WriteLine ("Jimmy Olsen")
Stream.Close
This example displays an open-file dialog box that lets the user select a QuickTime movie. The QuickTime movie is then copied into the Movie property of a MoviePlayer control.
f= GetOpenFolderItem("video/quicktime")
If f <> Nil then
MoviePlayer1.movie=f.OpenAsMovie
End if
This example copies all the files in a particular folder. The following code is a button's Action:
origin= SelectFolder
If origin <> Nil then
destination= SelectFolder
If destination <> Nil then
CopyFileOrFolder origin, destination
MsgBox "Copy complete!"
end if
end if
The CopyFileorFolder method is as follows:
Dim i as Integer
Dim newFolder as FolderItem
If...Then...Else source.directory then //it's a folder
newFolder=destination.child(source.name)
newFolder.createAsFolder
For i=1 to source.count //go through each item
If source.item(i).directory then
//it's a folder
CopyFileOrFolder source.item(i), newFolder
//recursively call this
//routine passing it the folder
else
source.item(i).CopyFileTo newFolder
//it's a file so copy it
end if
next
else //it's not a folder
source.CopyFileTo destination
end if
Using GetRelative
Dim f,g as FolderItem
f= New FolderItem
g=f.GetRelative(f.GetSaveInfo( Volume(0).Child("Documents"),0))
Statictext2.text=g.Absolutepath
See Also
GetFolderItem, GetOpenFolderItem, GetSaveFolderItem, SelectFolder, Volume, VolumeCount functions; BinaryStream, FolderItemDialog, OpenDialog, SaveAsDialog, SelectFolderDialog, TextInputStream, TextOutputStream classes.